Summary

Adds opt-in support for running multiple isolated Microsoft OpenTelemetry SDK instances in a single Node.js runtime. Today useMicrosoftOpenTelemetry() registers global providers per signal, so a second initialization clobbers the first. This PR introduces a parent/child delegating-provider architecture so independent pipelines can coexist — and, crucially, each instance owns its own set of OpenTelemetry instrumentations, settings, and sampling, bound directly to that instance's providers.

The prioritized scenario this enables: a customer registers different instrumentations for the Azure Monitor exporter than for the A365 (or OTLP) exporter in the same process (e.g. full HTTP/SQL/Redis to Azure Monitor, GenAI-only to A365).

GA constraint respected: all changes are additive and non-breaking. The existing single-instance useMicrosoftOpenTelemetry() path is untouched.

What's new

• createMicrosoftOpenTelemetryInstance(options, { makeDefault? }) returns a MicrosoftOpenTelemetryInstance handle (getTracer/getMeter/getLogger, runWithInstance, forceFlush, shutdown). Each instance builds a standalone pipeline plus its own instrumentations, sampler, and exporter.
• runWithMicrosoftOpenTelemetryInstance(id, fn) binds an ambient current instance so code using the global OTel API routes to the right pipeline.

Design

src/distro/multiInstance/:

• instanceRegistry.ts — registry + default instance + AsyncLocalStorage-backed ambient current instance.
• delegatingProviders.ts — Parent Tracer/Meter/Logger providers that resolve the current child per call (never cached) and delegate, with Noop fallbacks.
• globalSetup.ts — registers the parent providers + a single shared context manager + composite propagator exactly once, and installs the SDKStats instrumentation patcher once.
• instance.ts — builds each child as standalone NodeTracerProvider/MeterProvider/LoggerProvider (no NodeSDK.start(), no global registration), wiring Azure Monitor handlers, A365 export, caller processors, and a console fallback. It then builds this instance's instrumentations from its own instrumentationOptions and binds them to the child providers via registerInstrumentations, before registering the instance.

Per-instance instrumentations (the key mechanism). Because each instrumentation is bound directly to its instance's providers, the spans/metrics/logs it produces flow only to that instance's exporter. Two instances with different instrumentationOptions therefore feed their respective exporters with different instrumentation sets. Auto-instrumentation does not depend on the ambient current instance and bypasses the delegating providers; those parents remain the routing mechanism only for manual telemetry created through the global OpenTelemetry API (trace.getTracer(...)), which still resolves to the ambient (via runWithInstance) or default instance.

A365 export & defaults. Each instance can target A365 (A365SpanProcessor + Agent365Exporter). When an instance targets A365 without Azure Monitor, the A365 GenAI-focused instrumentation defaults are applied per instance. _applyA365InstrumentationDefaults was moved into src/distro/instrumentations.ts and is now shared by both the single- and multi-instance paths (re-exported from distro.ts for existing consumers).

Third-party instrumentations & touching globals

Registering a third-party instrumentation. The per-instance instrumentationOptions covers the built-in set (HTTP, Azure SDK, DB clients, loggers, GenAI). To add an arbitrary third-party OpenTelemetry instrumentation, a customer registers it the standard OTel way and does not pass a provider:

import { registerInstrumentations } from "@opentelemetry/instrumentation";
registerInstrumentations({ instrumentations: [new SomeThirdPartyInstrumentation()] });

When no tracerProvider/meterProvider/loggerProvider is supplied, OTel binds the instrumentation to the global providers — which, after ensureGlobalSetup(), are our delegating parent providers. So the third-party instrumentation transparently receives delegating tracers/meters/loggers.

How its telemetry is routed. The delegating provider resolves the target instance per call (never cached): the ambient instance bound by runWithInstance, else the default instance. So:

• Telemetry the instrumentation emits while the customer's workload runs inside instance.runWithInstance(() => …) lands on that instance's exporter.
• Outside any runWithInstance, it lands on the default instance.
• Before any instance exists, the Noop fallbacks make the calls safe (they never throw), rather than crashing instrumentation that loads early.

Why "touching globals" is safe. A third-party instrumentation (or an SDK it bundles) may reach for process-global OTel state. Each case is handled:

• Re-registering global providers (trace.setGlobalTracerProvider, metrics.setGlobalMeterProvider, logs.setGlobalLoggerProvider): the OTel API honors only the first registration and turns later calls into a no-op (with a diag warning). ensureGlobalSetup() installs the delegating parents once, up front, and the child providers are deliberately never set as global. A third-party instrumentation therefore cannot overwrite the delegators, hijack routing, or pin all telemetry to a single pipeline.
• Reading the global provider (trace.getTracerProvider() / getTracer): returns the delegating parent, so it inherits the per-call routing above.
• Context manager & propagators (context.setGlobalContextManager, propagation.setGlobalPropagator): also once-only, and installed once by ensureGlobalSetup() as a single shared AsyncLocalStorageContextManager + CompositePropagator. Context and propagation are intentionally process-wide and shared by every instance (the ambient current instance id itself rides on the active context), so a third-party instrumentation using context.active()/.with()/propagation interoperates correctly and can't install a competing manager.
• Module monkey-patching (patching http, a DB driver, etc.): this is inherently process-global and independent of providers. Because the instrumentation holds a delegating tracer, the patched code still emits into whichever instance is ambient at call time. If two instances enable the same built-in instrumentation, each gets its own instrumentation object bound to its own providers; the underlying module may be wrapped by both (standard OTel behavior), but each wrapper carries its own instance-bound tracer, so spans still land on the correct instance.
• SDKStats bookkeeping: the autoloader enableInstrumentations patch is installed once in ensureGlobalSetup(), so third-party registrations are still counted.

Deterministic binding (note). Built-in per-instance instrumentations are bound directly to their instance's providers, so they need no ambient context. A globally-registered third-party instrumentation instead routes via the ambient/default instance; to pin it deterministically to one instance, run the workload it observes inside that instance's runWithInstance(...). A future enhancement could accept instrumentations?: Instrumentation[] in the per-instance options and bind them directly, matching the built-in behavior.

Testing

• test/internal/functional/multiInstance.test.ts:
  • Two instances with distinct connection strings — each instance's spans reach only its own exporter, and global-API spans inside runWithInstance route to the bound instance.
  • New: two instances with different instrumentationOptions (HTTP on for A, off for B) bind different instrumentation sets to distinct providers — verifying per-exporter instrumentation.
• Verified end-to-end with a standalone Node app: two instances in one process — A (Azure Monitor, HTTP+Azure SDK on, 100% sampling) and B (console, HTTP off, 25% sampling). The outgoing HTTPS request produced an HTTP dependency span on A only; sampling kept 40/40 on A and ~10/40 on B; Azure Monitor transmitted with no errors.
• Full unit + functional suites green (910 passed); ESM + CJS build, lint, and format pass.

Dependencies

• Promotes @opentelemetry/context-async-hooks from transitive to a direct dependency (imported directly to register the context manager, since the multi-instance path does not call NodeSDK.start()). No overrides used.